home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / games / nhak_src.zip / OVLMGR.DOC < prev    next >
Text File  |  1993-03-16  |  14KB  |  297 lines
  1.              Brief notes about ovlmgr.asm
  2.              ----------------------------
  3.              (revised 1990may27)
  4.  
  5. OVLMGR.ASM is a preliminary version of a multiple-residency overlay
  6. manager for use with the Microsoft Overlay Linker.  It is functionally
  7. compatible with the one in the MSC library _except_:
  8.  
  9. - it usually accesses the disk less often and is a lot faster in some
  10.   applications.
  11. - it has different tuning characteristics.
  12. - you must (of course) link OVLMGR.OBJ into the root overlay (that is,
  13.   outside any parentheses in the link command).
  14.  
  15.   See also the notes below.
  16.  
  17.     As with other Microsoft-compatible overlay handlers you must be
  18. *very* careful never to call a function in an overlay through a pointer,
  19. unless the initiator of the call resides in the *same* physical overlay
  20. as the target (1).  Furthermore, setjmp() and longjmp() are not
  21. supported.
  22.  
  23.     Unlike the Microsoft system, most of the available memory is
  24. used to hold overlays.    Care must be taken to ensure that enough space
  25. is reserved for the C heap.  This can be accomplished through
  26. information stored in the .EXE file (currently the minalloc parameter,
  27. as described below).
  28.  
  29.        Furthermore, expanded memory support (EMS) is now an integral
  30. part of the overlay manager.  LIM EMS versions 3.2 and 4.0 are
  31. supported.  Note that the page frame must be 4 pages long (64K bytes) to
  32. be able to operate correctly (most drivers allocate a 64K frame by
  33. default).  The overlay manager will use as much EMS as is necessary in
  34. 64K chunks, up to a limit of 16 chunks (1 Meg).  Both hardware and
  35. software EMS drivers have been tested and found to be completely
  36. compatible.
  37.  
  38.                 ~ * ~
  39.  
  40.     OVLMGR.ASM currently has two assembly-time options, which are
  41. specified with the assembler's /D<symbol> option (or compatible).  They
  42. are:
  43.  
  44.     /DNOEMS Disable EMS support.
  45.         OVLMGR normally detects the presence of EMS memory and
  46.         makes use of it whenever it is present.  This flag
  47.         instructs ovlmgr to ignore EMS and operate only out of
  48.         conventional memory.  It should be used when overlaying
  49.         programmes which expect to use EMS themselves.
  50.  
  51.     /Di386    Use 80386-specific instruction sequences.
  52.         Use of this flag will make ovlmgr perform better on
  53.         machines with 80386 processors.  However, the resulting
  54.         programme will not run at all on machines with less
  55.         capable CPUs.  Use this option with caution, especially
  56.         in the case of distribution code.
  57.  
  58.                 ~ * ~
  59.  
  60.     Although using the overlay manager is in essence much like using
  61. Microsoft's, they operate on a slightly different principle, and tuning
  62. for them is rather different.  Technical part begins.
  63.  
  64.     When overlay linking is requested (see your linker manual), the
  65. MS overlay linker changes all far calls into overlays from the (normal,
  66. 8086) format:
  67.  
  68.     offset    contents
  69.     ------    --------
  70.     :0000    CALL
  71.     :0001    target-offset
  72.     :0003    target-segment
  73.  
  74. to this:
  75.     :0000    INT
  76.     :0001    int#    target-mod#
  77.     :0003    target-offset
  78.  
  79. (note that here we are looking at the actual layout of the machine
  80. code, not at the assembly code as such) and relocates the code parts
  81. of all the different overlays into the *same* physical area.  The
  82. overlaid code is all actually placed at the end of the .EXE file,
  83. after the 'normal' executable image, along with all its administrative
  84. data (fixups etc.).
  85.  
  86.     When this altered 'call' is executed, of course, the interrupt
  87. handler int# is invoked.  Its job is to ensure that the target overlay
  88. module is in memory (reading it from the tail of the .EXE file if it
  89. isn't already loaded) and then transfer to the given offset within it,
  90. 'faking up' the effect of the 'real' far call that would normally have
  91. occurred.  Something similar must be done when the call returns, to
  92. ensure that the thing being returned *into* is still (or is once more)
  93. loaded.
  94.  
  95.     The Microsoft linker, as we have said, relocates all the
  96. overlays to the same load address; and, in fact, it allocates am empty
  97. block of memory there that is at least as large as the largest
  98. overlay.  Into this area all the overlays are loaded without further
  99. change; thus, there can only ever be one overlay in memory at one
  100. time.  Transferring from one overlay to another causes one overlay to
  101. replace the other in the allocated overlay swap area.
  102.  
  103.        Our overlay manager does not use the space allocated by the
  104. linker in the same way.  Rather, it allocates almost all of the memory
  105. available from MS-DOS (including the original overlay area and any high
  106. DOS memory) as well as EMS memory if some is available and that option
  107. is being used.    As overlays are needed, they are loaded wherever they
  108. will fit, and dynamically relocated to that address.  Thus, many more
  109. than one overlay may be loaded at any given time, greatly increasing
  110. potential performance.    Management of space is more or less according to
  111. an LRU policy - once all of memory is full, the least recently used
  112. overlay is selected as the most likely candidate for replacement.
  113.  
  114.     The implications of this difference are as follows:  while with
  115. the conventional (default) overlay manager, the best strategy is to
  116. group object modules together in an overlay whenever they are known to
  117. be used in rapid succession, to make each overlay as big as possible
  118. (all things being equal) in order to take advantage of all available
  119. memory, and to make as few overlays as possible (to reduce the amount of
  120. disk access), the best strategy with our overlay manager is almost the
  121. reverse.  Having a lot of small overlays will increase the amount of
  122. useful stuff that can be resident in memory at the same time; all of
  123. memory will automatically be employed; and there is no advantage at all
  124. to uniformity of size (except perhaps in the unlikely case of *exact*
  125. uniformity!).
  126.  
  127.     Although ovlmgr allocates all available memory while it is
  128. active, you will find that the DOS exec() call works normally.    The
  129. memory that is allocated for administering the overlay system is freed
  130. before the exec call is made and reallocated afterwards (we trap the DOS
  131. function request vector to do this, which isn't very nice as a
  132. programming practise but makes the existence of the overlay manager far
  133. more transparent).  There is, however, one circumstance under which this
  134. can be problematic:  if you use the exec() call to load a TSR
  135. application, thereby causing memory that the overlay manager was using
  136. to become unavailable, you may make it impossible for the overlaid
  137. application to proceed.  This is because code that is nominally
  138. 'running' (i.e. is currently on the stack) cannot be relocated and must
  139. be reloaded at the *same address* that previously held it.  If another
  140. process now owns that area of memory, there is nothing we can do.  We
  141. believe that this should not be a serious concern in normal use.
  142.  
  143.                 ~ * ~
  144.  
  145.     Since all available memory is potentially used by ovlmgr, there
  146. is one additional concern in using it with C programmes:  the allocation
  147. of sufficient space for the C heap (2).  While previous versions of
  148. ovlmgr.asm required the change of an internal constant and re-assembly
  149. of ovlmgr to change the amount of space pre-allocated for this purpose,
  150. the current version uses the DOS minalloc parameter in the executable
  151. file to hold the size of the desired heap area.  This parameter can be
  152. set at any time after the link process with either Microsoft's exemod
  153. utility or with the supplied utility, exesmurf.
  154.  
  155.                 ~ * ~
  156.  
  157. NOTA BENE: This is a preliminary version of the overlay manager, but
  158. by now it should be fairly well debugged. If you are considering
  159. upgrading it please be aware that the following improvements are
  160. planned for the next version (though who knows when delivery will
  161. occur):
  162.  
  163.       - compatible versions of setjmp() and longjmp()
  164.       - integral malloc() to eliminate the heap size guesswork
  165.       - support for swapped data areas (read-only and read/write)
  166.       - improved performance through dynamic link-loading (maybe)
  167.       - XMS support and improved EMS support
  168.       - support for divergent-functionality overlays (such as
  169.       hardware-specific modules)
  170.       - enabling the overlay locking code
  171.       - Major code revamping
  172.  
  173. Swap On!
  174.  
  175. ------------------------------------------------------------------------
  176. MESSAGES
  177.  
  178. OVLMGR: Not enough free memory left to run this program.
  179.  
  180.     Although DOS successfully loaded the programme, it proved
  181.     impossible to allocate enough additional contiguous memory to
  182.     load one or more of the overlays.  Either reduce the
  183.     RAM-loading of the application by reducing the size of either
  184.     the root or the largest overlays, or increase the amount of
  185.     memory available by unloading TSRs and/or simplifying your
  186.     CONFIG.SYS.
  187.  
  188. OVLMGR: Internal memory allocation failure.
  189.  
  190.     Either an internal error has occurred in ovlmgr or the
  191.     application programme, or some event has caused memory that
  192.     ovlmgr believed it could count on becoming unavailable.  A
  193.     typical example of the latter would be the result of
  194.     attempting to load a TSR while an overlaid application is
  195.     running.
  196.  
  197. OVLMGR: Inaccessible EXE file. Can't load overlays.
  198.  
  199.     For some reason ovlmgr could not locate or read the original
  200.     .EXE file in which the overlays reside.  This could be due to
  201.     your attempting to use a very old version of DOS,
  202.     an abject shortage of file handles, some strange event causing
  203.     the file to be deleted, a disk error, or the diskette that
  204.     contained the executable being removed.
  205.  
  206. OVLMGR: Incorrect DOS version. Must be 3.00 or later.
  207.  
  208.     The current version of ovlmgr does not support versions of DOS
  209.     prior to 3.0 because of the difficulty of locating the
  210.     executable file (and hence the overlays) at runtime.
  211.  
  212. OVLMGR: EMS memory manager error.
  213.  
  214.     An error occurred during an EMS access.  Either the hardware has
  215.     reported a bug, the software driver has detected an anomaly or
  216.     the page frame is not 64K bytes in length.
  217.  
  218. (xxxx:xxxx:xxxx:xxxx)
  219.  
  220.     This is a diagnostic code composed of the following fields:
  221.         - error code
  222.         - version number
  223.         - available conventional memory
  224.         - EMS memory usage
  225.     Please note it in any bug reports or correspondence with the
  226.     development team.
  227.  
  228. ------------------------------------------------------------------------
  229. KNOWN BUGS
  230.  
  231. The present version cannot always be used as a direct replacement for
  232. Microsoft's overlay manager (even granted the documented differences)
  233. because the minimum size required for an overlaid programme to run is at
  234. least the size of the root plus TWICE the size of the largest overlay.
  235. If a programme has previously had its overlay structure tuned to take
  236. best advantage of Microsoft overlays, this may well cause a problem.
  237. The overlays themselves will need to be split up.
  238.  
  239. Transfers between overlays are very slow in machine terms, even if both
  240. overlays happen to reside in memory at the time (still significantly
  241. faster than Microsoft's, though).
  242.  
  243. Locking overlays into memory is not really implemented even though
  244. reading the source code might make you think it was.  Actually, reading
  245. the source code itself isn't very well implemented right now.  Comments
  246. and stuff would help.  Yup, yup.
  247.  
  248. Due to limitations in the LIM EMS standard (to 4.0), programmes that
  249. themselves use EMS memory cannot be overlaid with ovlmgr unless ovlmgr's
  250. own EMS support is disabled.  This is accomplished by assembling with
  251. the /DNOEMS flag.
  252.  
  253. ------------------------------------------------------------------------
  254. BUG ALERT
  255.  
  256. To repeat a point made above, if you ever try to call a function in an
  257. overlay through a pointer, you *may* die with the Microsoft overlay
  258. manager.  If you ever try to call a function in an overlay through a
  259. pointer, you *will* die with ours.  Nothing in an overlay ever ends up
  260. in the same segment as the linker anticipated.    You have been warned!
  261.  
  262. ------------------------------------------------------------------------
  263. FOOTNOTES
  264.  
  265. (1) This problem can be circumvented through the use of surrogate
  266. 'trampoline' functions:  functions that reside in the root overlay and
  267. simply pass right through to the 'real', overlaid, implementations.
  268. This can even be made transparent to the source code through the use
  269. of the C macro preprocessor, with a locution of the form
  270.     #define foo(x) foo_(x)
  271. visible everywhere except at the actual definition point of the
  272. trampoline.  This has been implemented in NetHack 3.0.
  273.  
  274. (2) If you should get a message to the effect that NetHack can't
  275. allocate 28000 and some bytes when entering a maze level, that
  276. isn't our problem!  In all probability you forgot to rebuild your
  277. special level files when you changed the compiler flags.  We got
  278. that one, too, at one point.  The same applies to similar messages when
  279. reading bones files or saved games:  it is more likely that you forgot
  280. to discard them after recompiling your game than that the memory
  281. allowance is so greatly incorrect.
  282.  
  283. ----------------------------------------------------------------------
  284. NOTICE
  285.  
  286. OVLMGR.ASM is brought to you by Pierre Martineau and Stephen Spackman.
  287. It, and this document, are copyright.  They are, however, provided as
  288. part of NetHack and may be freely distributed as described in the
  289. NetHack license.
  290.  
  291. ----------------------------------------------------------------------
  292. Stephen P Spackman                 stephen@tira.uchicago.edu
  293. Pierre G Martineau                  pierre@ozrout.uu.net
  294. ----------------------------------------------------------------------
  295.     Copyright (c) 1989, 1990 Pierre G Martineau and Stephen P Spackman
  296.     All Rights Reserved.
  297.